Customizing tool response

Reshaping the response

By default, the full response body returned by the tool is passed to the LLM. You can transform it first — to extract a single field, drop irrelevant elements, or trim a large payload — by configuring the Response reshape parameter on the tool's Response tab.

The expression is interpreted as either jq or JMESPath:

If it starts with ., it is evaluated as a jq statement.
Otherwise it is evaluated as a JMESPath statement.

Example 1 — extract a single field (jq). The following statement returns a single value from the response:

.weather.temperature_c

Example 2 — reshape into a compact object (JMESPath). A JMESPath statement can build a new object that keeps only the fields the LLM needs:

{city: location.city, temperature_c: weather.temperature_c, condition: weather.condition}

Reshaping is applied only to successful responses. If the response is not valid JSON, or the jq / JMESPath expression fails, the original response is preserved unchanged.

JMESPath statements can use two custom functions — from_utc(<iso8601>) and to_utc(<iso8601>) — that convert timestamps to / from the timezone given by the timezone variable.

Maximum response length

By default, responses from customer-defined tools are limited to 100K characters. This safeguard prevents malfunctioning tools from overloading the conversation history and helps control unnecessary LLM processing costs.

This default can be changed by configuring the Max response length parameter.

Error response

In case of an error customer-defined tools return generic error response to LLM.

This is done on purpose to prevent exposure of internal tool implementation / API details to the agent’s business logic.

Use the following Agent’s configuration parameter to make tool error response more explicit and include HTTP response and text fields:

{"explicit_tool_errors": true}

To enable this for a single tool instead of all of the agent's tools, set {"explicit_errors": true} in the tool's Advanced tab.

Response timeout

The Timeout (sec) parameter defines how long the agent waits for the tool's response. Note that the conversation is paused while the tool is executed. If your tool execution takes too long, consider playing progress messages to keep the caller engaged.

No tool response

For agents that are expected to always call tools, you can set the no_tool_error advanced configuration parameter to the error that will be returned to LLM if it tries to provide textual response.

{
  "no_tool_error": "Text responses are not supported. Use `play_url` tool."
}

Note that for most AI Agent deployments, setting this parameter is not appropriate and will completely break the agent’s behavior. Use this parameter with great caution and only when your prompt explicitly instructs LLM to never provide textual responses

Tool responses in message history

Tool responses are preserved in message history, by default. This provides the LLM with better context and enables it to respond to follow-up questions using tool results from previous utterances. However, this may be problematic if, for example, the tool response is very long, as it will increase the context size and correspondingly the conversation costs. In such cases, you can redact the specific tool’s responses from message history, by setting the Response in message history parameter to redact.